SGI Developer Toolbox 6.1/SGI Developer Toolbox 6.1 - Disc 4.iso/src/exampleCode/viewkit/xcontact/onlineHelp/sample.sgm

Text File | 1994-08-02 | 12.5 KB | 398 lines

<dochelp>

<!--
  ==================================================================
  This block denotes a SGML-style comment.

  For those that are unfamiliar with SGML, this sample file
  will try to cover the usage of a variety of the tags that
  are used in the XHELP DTD. The examples shown in this sample
  should be sufficient for a writer to produce a very high-quality,
  functional help document for use with an application.

  It is best to view this sample once it has been published,
  and then compare what you see in the viewing software to
  the actual tags displayed in this file.

  Each HelpTopic block written below displays how to use the
  DTD to implement specific elements/constructs. It should be
  fairly self-explanatory.

  A couple of things to look for when constructing/editing
  your SGML file:

    o Make sure a starting element tag has an associated
          end tag! If not, then the file will not compile
          properly. This is analagous to missing a bracket
          or paranthesis in a C program!

    o Ending elements can be fully-qualified to denote the
      element they are ending, such as "</HelpTopic>" or
      they can use the shorthand (but less obvious) notation
      of "</>".

    o SGML is NOT case sensitive! "HELPTOPIC" is the same
       as "helptopic", which is the same as "HelpTopic", etc.
  ==================================================================
-->

<HelpTopic HelpID="intro">
<Helplabel>SGI Sample SGML File</Helplabel>
<Description>
<para>This file contains examples using many of the constructs used
in the XHELP DTD.</>
<para>Notice that the general outline used for putting together
a help "card" is defined by this particular SGML block. The preceding tag
defines the title that will be displayed for this card. The area you
are currently reading is a description for the feature or function you
are documenting. It is not necessary to use each of these tags, although
the "HelpTopic" tag is required.</>

<para>A writer of help information may also wish to include a glossary
of terms. In that way, the documenter can tag terms within the text,
and have them display a specified definition from within the viewer.
A sample of this is: <glossterm>sgihelp</glossterm>.</>
<para>The actual definition for the term is found at the end of this
SGML sample.</>
</Description>
</HelpTopic>



<!--
  ==================================================================
  It's important to point out that the "HelpID" is the glue that
  binds the help text to the application, through the use of the
  provided Help API (library, header file).
  ==================================================================
-->

<HelpTopic HelpID="helpid_info">
<Helplabel>What is a HelpID?</Helplabel>
<Description>
<para>The HelpID attribute is used to by your application to
instruct the help server which help "card" to display. In this
case, sending the help server an ID of "helpid_info" would bring up
this particular block (or "card").</>
<para>The other "ID" is often used as an anchor point
(and should be used within an "ANCHOR" tag) for hypertext
links within your text. If you wish to refer to a particular card
one simply uses the ID as the anchor point for the link syntax.</>
</Description>
</HelpTopic>



<!--
  ==================================================================
  This section illustrates the simple usage of specifying a note,
  warning, tip, or caution within your help document.
  ==================================================================
-->

<HelpTopic HelpID="note_example">
<Helplabel><Anchor Id="AI003">Using Notes, Warnings or Tips Within a Paragraph</Helplabel>
<Description>
<para>Within the paragraph tag, there are a variety of text marking
mechanisms. Each of these delineations must appear as part of the
paragraph ("para") element.</>
<para>This area shows the documentor how a warning, note or "tip"
can be used within a persons's help text.</>

<para>
<warning><para>Be Careful. This is a warning.</></warning>
<note><para>For your information, this is a note.</></note>
<tip><para>When you prepare your help file, you may wish to include a tip.</>
</tip>
<caution><para>Use a caution tag when you wish to have the user use caution!</>
</caution>
</para>
</Description>
</HelpTopic>



<!--
  ==================================================================
  This next section illustrates how to display computer output,
  program listings, etc. within your help document.
  ==================================================================
-->

<HelpTopic HelpID="literal_example">
<Helplabel>Using Literals or Examples Within a Paragraph</Helplabel>
<Description>
<para>
This area shows the documentor how to implement specific examples within
their help text. It also describes how to the "literal" tag.</>
<para>
When used within a paragraph, the LiteralLayout tag
tells the viewing software to take this next block "as is",
with all accompanying new-lines and spacing left intact.</>
<Example>
<Title>Various Examples: ComputerOutput, LiteralLayout, ProgramListing</Title>

<para>
What follows is a computer output listing from when a
user typed <userInput>ls</userInput> :
<ComputerOutput>
% ls -l
total 6777
-rwxr-xr-x  1 guest  guest   29452 Mar  8 19:12 menu*
-rw-r--r--  1 guest  guest    2375 Mar  8 19:11 menu.c++
%
</ComputerOutput>
</para>

<para>
Each of the subsequent three entries should be indented and on their
own line:
<LiteralLayout>
    Here is line one.
    This is line two.
    This is line three.
</LiteralLayout>
</para>

<para>
The following is a listing from a "C" program:
<ProgramListing>
    #include "X11/Xlib.h"
    #include "helpapi/HelpBroker.h"

    void main(int, char**)
    {
         /* default to the value of the DISPLAY env var */
         Display *display = XOpenDisplay(NULL);

         if( display ) {
               /* initialize the help server */
               SGIHelpInit(display, "MyApp", ".");
         }
         ...
    }
</ProgramListing>
</para>
</Example>

</Description>
</HelpTopic>



<!--
  ==================================================================
  This next section illustrates how to incorporate graphics within
  your help text.
  ==================================================================
-->

<HelpTopic HelpID="graphic_example">
<Helplabel>Using Graphics or Figures Within Your Help Text</Helplabel>
<Description>
<para>
This area displays how a graphics or figure can be used within the flow of
your information. The following figure is in the "GIF" format:
</para>

<Figure ID="figure_01" Float="Yes">
    <title>A GIF Raster Image</title>
    <Graphic fileref="sample1.gif" format="GIF"></>
</Figure>

<para>
Currently, support is provided for <emphasis>raster</emphasis> graphics in
the GIF and TIF formats. Support is provided for <emphasis>vector</emphasis>
graphics utilizing the CGM format.
</para>
<para>
This next figure in the CGM (Computer Graphics Metafile) format:
</para>

<Figure ID="figure_02">
    <title>A CGM Vector Image</title>
    <Graphic fileref="sample2.cgm" format="CGM"></>
</Figure>

<para>
A special note that all equations are treated as inline images, as shown
here:
<equation>
    <Graphic fileref="matrix.gif" format="GIF"></>
</equation>
</para>

</Description>
</HelpTopic>



<!--
  ==================================================================
  Hyperlinks can be a very powerful navigation mechanism!
  Liberal usage is encouraged.
  ==================================================================
-->

<HelpTopic HelpID="link_example">
<Helplabel>Using HyperLinks</Helplabel>
<Description>
<para>One of the most powerful capabilities of the sgihelp viewer
is the use of hyperlinks to associate like pieces of information.
Constructing these links in SGML is trivial.</>
<para>Notice that the "Link" element requires an attribute called
"Linkend". This defines the area (anchor) to link to. The "Linkend"
attribute points to the ID of some SGML element. In composing
help text, it is probably best to assign an ID to each "HelpTopic"
element, and use those same ID's when specifying a Link.</>
<para>A link is defined below:</>
<para>For more information about using Notes, refer to the area
entitled <Link Linkend="AI003">"Using Notes, Warnings or Tips
Within a Paragraph"</Link></>
<para>Note that the "Anchor" tag can also be used within a
document to point to any level of granularity the author
wishes to link to.</>
</Description>
</HelpTopic>



<!--
  ==================================================================
  Note that there are *many* ways to specify lists. This example
  shows some commonly-used permutations.
  ==================================================================
-->

<HelpTopic HelpID="list_example">
<Helplabel>Using Lists Within Your Help Text</Helplabel>
<Description>
<para>This area displays how a person can author
various types of lists within their help text.</para>

<para>Here is an itemized list that uses a dash to preface each item:</para>
<ItemizedList Mark="dash">
<ListItem><para>First Entry</></ListItem>
<ListItem><para>Second Entry</></ListItem>
<ListItem><para>Third Entry</></ListItem>
</ItemizedList>

<para>Here is an itemized list that uses a bullet to preface each item:</para>
<ItemizedList Mark="bullet">
<ListItem><para>First Entry</></ListItem>
<ListItem><para>Second Entry</></ListItem>
</ItemizedList>

<para>Here is an ordered list, using standard enumeration:</para>
<OrderedList>
<ListItem><para>First Entry</></ListItem>
<ListItem><para>Second Entry</></ListItem>
<ListItem><para>Third Entry</></ListItem>
</OrderedList>

<para>Here is another ordered list, using upper-case Roman enumeration,
showing nesting (sub-items) within the list (outline format):</para>
<OrderedList Numeration="Upperroman">
<ListItem><para>First Entry</></ListItem>
<ListItem><para>Second Entry
    <OrderedList Numeration="Upperalpha" InheritNum="Inherit">
        <ListItem><para>First SubItem</></ListItem>
        <ListItem><para>Second SubItem</></ListItem>
        <ListItem><para>Third SubItem</></ListItem>
        <ListItem><para>Fourth SubItem</></ListItem>
    </OrderedList>
</></ListItem>
<ListItem><para>Third Entry</></ListItem>
</OrderedList>

<para>Here is a variable list of terms:</para>
<VariableList>
<VarListEntry>
<term>SGI</term>
<ListItem><para>Silicon Graphics, Inc.</></ListItem>
</VarListEntry>
<VarListEntry>
<term>SGML</term>
<ListItem><para>A Meta-language for defining documents.</></ListItem>
</VarListEntry>
</VariableList>

</Description>
</HelpTopic>



<!--
  ==================================================================
  Some final examples...
  ==================================================================
-->

<HelpTopic HelpID="misc_example">
<Helplabel>Other Miscellaneous Textual Attributes</Helplabel>
<Description>
<para>This area displays some miscellaneous tags that can be used
within the context of your help document.</para>

<para>
<Comment>This is a comment that is not to be confused
with the SGML-style comment! Instead, this comment will be
parsed and carried into the text of your document. Usually it's
used in production, for specifying to someone an area of concern,
an area that needs editing, etc.
</Comment>
</para>

<para>Within your text, you may wish to denote a footnote.
<Footnote id="foot1"><para>This block is a footnote!</></Footnote>
The XHELP DTD will allow you to do that.
</para>

<para>
You may wish to add a copyright symbol to your text, such as:
Silicon Graphics, Inc.<trademark Class="Copyright"></>
</para>
</Description>
</HelpTopic>



<!--
  ==================================================================
  If you wish to use/have a glossary of terms within your help text,
  it is advised to put it at the end of your help "book", as shown
  here. NOTE: CR or other characters (#PCDATA) is NOT allowed
  between the <Glossary> and <Title> tags! (mixed content model)
  ==================================================================
-->

<Glossary>
<Title>Glossary</Title>
<GlossEntry>
<GlossTerm>help</GlossTerm>
<GlossDef>
<para>To give assistance to; to get (oneself) out of a difficulty;
a source of aid.</>
</GlossDef>
</GlossEntry>
<GlossEntry>
<GlossTerm>sgihelp</GlossTerm>
<GlossDef>
<para>This is Silicon Graphics, Inc. version of a "Xhelp" compatible
server. Through the use of an available API, and a help text
compiler, books can be constructed that can be used to render
help information for the given application.</>
</GlossDef>
</GlossEntry></Glossary>


<!--
  ==================================================================
  Don't forget the very last ending tag...!!!
  ==================================================================
-->

</dochelp>